<html>

<head>
<title>Raytracing Functions</title>
<style type="text/css"><!--tt { font-size: 10pt } pre { font-size: 10pt }--></style>
</head>

<body bgcolor="#ffffff" text="#000000" link="#000080" vlink="#800000" alink="#0000ff">

<table border="0" cellpadding="0" cellspacing="0" bgcolor="#d0d0d0">
  <tr>
    <td width="120" align="left"><a href="meshinfo.html"><img width="96" height="20"
    border="0" src="images/navlt.gif" alt="Mesh Info"></a></td>
    <td width="96" align="left"><a href="filefmts.html"><img width="64" height="20" border="0"
    src="images/navrt.gif" alt="File Formats"></a></td>
    <td width="384" align="right"><a href="index.html"><img width="230" height="20" border="0"
    src="images/proglw.gif" alt="Table of Contents"></a></td>
  </tr>
</table>

<table border="0" cellpadding="0" cellspacing="0">
  <tr>
    <td width="600"><br>
    <h3>Raytracing Functions</h3>
    <p>Several plug-in classes receive pointers to raytracing functions that allow them to
    probe the scene from any point of view.</p>
    <p>These functions aren't valid in all contexts, since they depend on having information
    about the scene that may not always exist. When the Surface Editor renders its preview
    thumbnail, for example, it evaluates the active <a href="classes/shader.html">shaders</a>,
    but in this previewing context, the <tt>rayCast</tt> and <tt>rayShade</tt> fields of the
    LWShaderAccess will be NULL. Always ensure that raytracing function pointers are valid
    before using them.</p>
    <p>You may also need to safeguard against infinite recursion. A ray fired in the
    evaluation callback of a <a href="classes/shader.html">shader</a> or (particularly) a <a
    href="classes/volume.html">volumetric</a> may cause that callback to be re-entered.
    Shaders can use the <tt>bounce</tt> member of the LWShaderAccess to monitor the recursion
    level.</p>
    <pre>   typedef double LWRayTraceFunc (const LWDVector position,
                     const LWDVector direction, LWDVector color);

   typedef int    LWIlluminateFunc (LWItemID light,
                     const LWDVector position, LWDVector direction,
                     LWDVector color);

   typedef double LWRayCastFunc (const LWDVector position,
                     const LWDVector direction);

   typedef double LWRayShadeFunc (const LWDVector position,
                     const LWDVector direction,
                     struct st_LWShaderAccess *);</pre>
    <dl>
      <dt><tt>len = <strong>rayTrace</strong>( position, direction, color )</tt></dt>
      <dd>Trace a ray from the given location in the given direction in world coordinates. The
        return value is the length of the ray (or -1.0 if infinite) and the color coming from that
        direction. The direction argument is the outgoing direction and must be normalized (a unit
        vector). <dl>
          <dt><br>
            <tt>position</tt></dt>
          <dd>The world coordinates of the source of the ray.</dd>
          <dt><tt>direction</tt></dt>
          <dd>A unit-length vector, the outgoing direction of the ray in world coordinates.</dd>
          <dt><tt>color</tt></dt>
          <dd>Storage for the color of the spot hit by the ray.</dd>
        </dl>
      </dd>
      <dt><tt><br>
        lit = <strong>illuminate</strong>( lightID, position, direction, color )</tt></dt>
      <dd>This function obtains the light ray (color and direction) hitting the given position
        from the given light at the current time step. The return value is zero if the light does
        not illuminate the given world coordinate position at all. The color includes effects from
        shadows (if any), falloff, spotlight cones and transparent objects between the light and
        the point. <dl>
          <dt><br>
            <tt>lightID</tt></dt>
          <dd>The light, given by its LWItemID.</dd>
          <dt><tt>position</tt></dt>
          <dd>The world coordinates of the spot at which the illumination will be tested. </dd>
          <dt><tt>direction</tt></dt>
          <dd>Storage for the direction of the light ray computed by the function.</dd>
          <dt><tt>color</tt></dt>
          <dd>Storage for the color of the light ray. </dd>
        </dl>
        <p>Two special light IDs, <tt>LWITEM_RADIOSITY</tt> and <tt>LWITEM_CAUSTICS</tt>, allow <a
        href="classes/shader.html">shaders</a> and <a href="classes/pxlfilt.html">pixel filters</a>
        to account for global illumination. When using these IDs, the <tt>direction</tt> argument
        becomes an input rather than an output, specifying the desired sampling direction. </p>
      </dd>
      <dt><tt>len = <strong>rayCast</strong>( position, direction )</tt></dt>
      <dd>This is a quicker version of the rayTrace function which only returns the distance to
        the nearest surface (or -1.0). It performs neither shading nor recursive raytracing. <dl>
          <dt><br>
            <tt>position</tt></dt>
          <dd>The world coordinates of the source of the ray.</dd>
          <dt><tt>direction</tt></dt>
          <dd>A unit-length vector, the outgoing direction of the ray in world coordinates.</dd>
        </dl>
      </dd>
      <dt><br>
        <tt>len = <strong>rayShade</strong>( position, direction, shaderAccess )</tt></dt>
      <dd>Trace a ray to the nearest surface and evaluate the basic surface parameters and any
        shaders on that surface. The <a href="classes/shader.html#access">LWShaderAccess</a>
        structure passed (and owned) by the caller is filled in with the result and no more
        processing is done. <dl>
          <dt><br>
            <tt>position</tt></dt>
          <dd>The source of the ray in world coordinates.</dd>
          <dt><tt>direction</tt></dt>
          <dd>A unit-length vector, the outgoing direction of the ray in world coordinates.</dd>
          <dt><tt>shaderAccess</tt></dt>
          <dd>A pointer to an empty ShaderAccess structure that will be filled in by the function.</dd>
        </dl>
      </dd>
    </dl>
    </td>
  </tr>
</table>
</body>
</html>
